zlib: add ZIP archive support to zlib (ZipFile,ZipBuffer,ZipEntry) by pipobscure · Pull Request #64339 · nodejs/node

pipobscure · 2026-07-07T14:54:34Z

Summary

Add ZIP archive support to the node:zlib module through three classes
and a set of helpers:

ZipEntry: a single archive member, with buffered reads (content()),
bounded-memory streaming reads (contentIterator()), and
create()/createStream() for building members.
ZipFile: random access to an archive backed by a file descriptor,
reading members lazily without retaining their content and writing
new members in place; opened with open()/openSync().
ZipBuffer: a zero-copy, in-memory view over an archive already held
in a Buffer.

createZipArchive() serializes a sequence of entries into an archive
byte stream, and setMaxZipContentSize() bounds the default in-memory
decompression size. Every operation has both an asynchronous and a
synchronous form.

P.S.: my CLA should be on file and I wrote this myself so COO is declared

codecov · 2026-07-07T16:32:30Z

Codecov Report

❌ Patch coverage is 95.76306% with 103 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.31%. Comparing base (1912893) to head (701dffd).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/zip.js	95.72%	94 Missing and 9 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #64339      +/-   ##
==========================================
+ Coverage   90.25%   90.31%   +0.05%     
==========================================
  Files         741      742       +1     
  Lines      241165   243596    +2431     
  Branches    45423    46034     +611     
==========================================
+ Hits       217673   219994    +2321     
- Misses      15069    15157      +88     
- Partials     8423     8445      +22

Files with missing lines	Coverage Δ
lib/internal/errors.js	`97.71% <100.00%> (+<0.01%)`	⬆️
lib/zlib.js	`98.36% <100.00%> (+0.02%)`	⬆️
lib/internal/zip.js	`95.72% <95.72%> (ø)`

... and 23 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Codecov flagged low patch coverage on lib/internal/zip.js and lib/internal/vfs/providers/archive.js in nodejs#64339. Add tests exercising Zip64 extra-field parsing, DOS date/time edge cases, streaming-entry state guards, decodeMemberStream/decodeMemberSync's duplicated error branches, the ZipBuffer/ZipFile iteration protocols, several on-disk ZipFile error paths, and ArchiveFileHandle's direct read/write/stat/ truncate surface plus a handful of provider-level error branches the existing tests didn't reach.

bakkot · 2026-07-07T23:15:44Z

See also #45651

pipobscure · 2026-07-08T05:42:44Z

See also #45651

Thanks @bakkot !!!

I think the time has come for it on the one hand, and on the other I added some „motivation“ links earlier. Here some more detail:

Based on this, we can modify the loader to directly load from an archive. If we do that, we get application bundles. pipobscure#5 & pipobscure#6

Which can then in turn be used to easily create application bundles: https://github.com/pipobscure/experimental-sea

So the world had changed enough that it‘s worth proposing again.

mcollina · 2026-07-08T13:00:36Z

I like this a lot. It's likely better to split this into 2 PRs, one for Zip support and one for VFS-Zip, so the Zip support could theoretically be backportable on its own.

mcollina · 2026-07-08T13:03:16Z

+  writeFileSync('archive.zip', await zip.toBuffer());
+}
+main();
+```


Does this support streamed reading? In other words, do we need to load the full buffer in memory?

Given that ZIP files have their Central Directory at the end, streaming (as in over the network) isn't really a thing. However in terms of reading from a ZipFile, then the asnwer is yes. It loads the Directory into memory. After that it knows exactly the bytes it needs to read a file, so it does a partial file read. So no you don't need to load the entire archive into memory. (I hope I understood what you are asking)

I validated streaming again. Yes it's does fully streaming reads and writes.

Read: create a stream directed at the file (offset based) and pipe through decompression.
Write: ZipEntry.createStream(inputstream) and then createZipArchive([ entry ]) which creates a Readable that can be piped. The input stream is consumed as the output stream is written.

So both directions are fully streamable (with the mentioned exception in reading requiring the end of the data to be available)

If we could support that via some kind of API, it would be awesome. To repeat: instead of a Buffer, specify a filename to be read in chunks.

This can also be a separate API, in case we want it to be made async.

Do you mean something like

createZipFromFiles([ filename1, filename2, filename3 ])

that just creates a Redable that can be piped?

The difficulty is that the name inside the archive isn't the absolute filename. Where do you cut it off?
If we want a simple createZipFromFolder(absoluteFolder) that creates a Readable, then give me 5 minutes.

Alternatively we could do:

createZipArchiveSomething([ [ fullpath, nameinarchive ] ])

pipobscure · 2026-07-08T16:32:01Z

As per @mcollina I split this into two PRs.

I have the vfs-provider ready to go as follow up one (as it depends on this being merged)

I also made sure that the streaming side of things was actually as clean as I intended, and added a few more tests.

Add ZIP archive support to the node:zlib module through three classes and a set of helpers: - ZipEntry: a single archive member, with buffered reads (content()), bounded-memory streaming reads (contentIterator()), and create()/createStream() for building members. - ZipFile: random access to an archive backed by a file descriptor, reading members lazily without retaining their content and writing new members in place; opened with open()/openSync(). - ZipBuffer: a zero-copy, in-memory view over an archive already held in a Buffer. createZipArchive() serializes a sequence of entries into an archive byte stream, and setMaxZipContentSize() bounds the default in-memory decompression size. Every operation has both an asynchronous and a synchronous form. Signed-off-by: Philipp Dunkel <pip@pipobscure.com>

bakkot · 2026-07-08T17:47:34Z

Might be worth borrowing some tests from other projects: e.g. python, go, info-zip. There's a lot of edge cases with zip files. (Python's tests are larger than this whole PR put together.)

Not all directly applicable because this doesn't include the ability to extract to disk, fortunately.

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jul 7, 2026

pipobscure changed the title ~~zlib, vfs: add ZIP archive read/write support and an archive vfs provider~~ zlib, vfs: add ZIP archive support and an archive vfs provider Jul 7, 2026

This comment was marked as outdated.

Sign in to view

pipobscure force-pushed the ziparchives branch 3 times, most recently from 0f2b879 to 4258e94 Compare July 7, 2026 19:20

pipobscure force-pushed the ziparchives branch 2 times, most recently from 2a56a15 to 27ab6b4 Compare July 7, 2026 21:54

jasnell reviewed Jul 8, 2026

View reviewed changes

Comment thread doc/api/vfs.md Outdated

JakobJingleheimer self-requested a review July 8, 2026 08:40

pipobscure force-pushed the ziparchives branch 2 times, most recently from f157686 to 233f865 Compare July 8, 2026 11:29

mcollina reviewed Jul 8, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

pipobscure force-pushed the ziparchives branch from 233f865 to 26fb1ab Compare July 8, 2026 16:22

pipobscure changed the title ~~zlib, vfs: add ZIP archive support and an archive vfs provider~~ zlib, vfs: add ZIP archive support to zlib Jul 8, 2026

mcollina reviewed Jul 8, 2026

View reviewed changes

Comment thread test/parallel/test-zlib-zip-vfs.js Outdated

pipobscure force-pushed the ziparchives branch from 26fb1ab to 701dffd Compare July 8, 2026 16:44

pipobscure changed the title ~~zlib, vfs: add ZIP archive support to zlib~~ zlib: add ZIP archive support to zlib (ZipFile,ZipBuffer,ZipEntry) Jul 8, 2026

Uh oh!

Uh oh!

Conversation

pipobscure commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

codecov Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as outdated.

bakkot commented Jul 7, 2026

Uh oh!

Uh oh!

pipobscure commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina commented Jul 8, 2026

Uh oh!

mcollina Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

pipobscure Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

pipobscure Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

mcollina Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

pipobscure Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pipobscure Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

pipobscure commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bakkot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pipobscure commented Jul 7, 2026 •

edited

Loading

codecov Bot commented Jul 7, 2026 •

edited

Loading

pipobscure commented Jul 8, 2026 •

edited

Loading

pipobscure Jul 8, 2026 •

edited

Loading

pipobscure commented Jul 8, 2026 •

edited

Loading

bakkot commented Jul 8, 2026 •

edited

Loading